Skip to content

Restore legacy permalink behavior using :filepath pattern - #5661

Open
dimaslanjaka wants to merge 1 commit into
hexojs:masterfrom
dimaslanjaka:filepath-permalink
Open

Restore legacy permalink behavior using :filepath pattern#5661
dimaslanjaka wants to merge 1 commit into
hexojs:masterfrom
dimaslanjaka:filepath-permalink

Conversation

@dimaslanjaka

@dimaslanjaka dimaslanjaka commented May 5, 2025

Copy link
Copy Markdown
Contributor

What does it do?

This PR introduces or adjusts the :filepath permalink pattern to replicate the previous behavior of :title, which was based on the post's file name and path under source/_posts/.

✅ What this PR does:

  • Restores old permalink behavior via :filepath
  • Enables backward compatibility for existing blogs without requiring manual changes to thousands of posts
  • Preserves legacy URLs and helps prevent SEO regressions or broken external links

🧪 How to test:

  1. Add the following to your _config.yml:
    permalink: :filepath/
  2. Make sure your posts inside source/_posts/ generate the expected permalinks matching the file name.

📌 Related Issue / Discussion:

🙏 Note:

This change helps long-time users maintain their blog structure and avoid unnecessary mass edits due to the breaking permalink change. Especially for blogger/wordpress users who have migrated to Hexo.

🔍 Test Results:

All posts render with the expected permalink structure using the :filepath pattern.

Issue resolved: #5658

Screenshots

image
image

Pull request tasks

  • Add test cases for the changes.
  • Passed the CI test.

@github-actions

github-actions Bot commented May 5, 2025

Copy link
Copy Markdown

How to test

git clone -b filepath-permalink https://github.com/dimaslanjaka/hexo.git
cd hexo
npm install
npm test

@stevenjoezhang

Copy link
Copy Markdown
Member

Thanks for working on a backward-compatible permalink option. I agree that a dedicated :filepath pattern is a reasonable approach, but I found a few issues that should be addressed before merging:

  1. The new test imports Hexo from 'hexo'. The repository cannot resolve itself by package name in this context, so the test fails with TS2307: Cannot find module 'hexo'. Please use:

    import Hexo from '../../../lib/hexo';
  2. The implementation hard-codes the default source/ directory. With a custom configuration such as source_dir: content, _posts/nested/foo.md produces:

    content/_posts/nested/foo.html
    

    instead of:

    nested/foo.html
    
  3. Draft sources are not handled. _drafts/nested/foo.md currently produces _drafts/nested/foo.html, so the URL changes after the post is published.

Since Post.source already contains the path relative to source_dir, the implementation could be simplified to:

const relativeSourcePath = data.source
  .replace(/\\/g, '/')
  .replace(/^_(?:posts|drafts)\//, '')
  .replace(/\.[^/.]+$/, '');

Please also add regression tests for a custom source_dir and an _drafts/ source. I tested this approach against the existing permalink tests plus those two cases, and all 22 related tests passed.

One more note: no GitHub Actions checks are currently reported for this PR, despite the CI checkbox being marked as completed. Rebasing onto the latest master should allow the current checks to run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

permalink :title changed without backward-compatible replacement

2 participants